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Introduction 


The  Compressed  Aeronautical  Chart  (CAC)  database  is  a  global  library  of  compressed,  scanned, 
aeronautical  charts  that  support  Navy  and  Marine  Corps  aircraft  moving-map  displays  and 
mission  planning  systems.  The  source  for  the  CAC  library  is  the  National  Imagery  and  Mapping 
Agency  (NIMA)  standard  ARC  (equal  Arc-second  Raster  Chart)  Digitized  Raster  Graphics 
(ADRG)  image  data  set.  ADRG  is  compressed  and  transformed  into  CAC  via  vector 
quantization  and  color  compression  techniques.  The  Map  Data  Formatting  Facility  (MDFF)  of 
the  Naval  Research  Laboratory,  Stennis  Space  Center,  MS  (NRLSSC),  produced  the  CAC  library 
from  April,  1989,  until  September,  1995, 
when  NRLSSC  transitioned  the  CAC 
Production  System  to  NIMA. 

NIMA  distributes  CAC  installments  on 
Compact  Disk  Read-Only  Memory 
(CDROM).  Each  CDROM  contains  data  at 
one  of  seven  available  chart  scales,  from 
1:5M  (M=million)  to  1:50k  (k=thousand),  as 
listed  in  table  1.  As  of  1995,  there  were  34 
CDROMs  in  the  CAC  library  (table  3).  For  a 
more  recent  listing,  the  reader  is  referred  to 
NIMA  Customer  Support. 

Table  2.  TS  geographic  zones 

CAC  data  is  structured  according  to  the 
Tessellated  Spheroid  (TS)  map  projection 
system.  TS  divides  the  world  into  five  zones 
(table  2).  Each  zone  is  divided  into  rows  and 
columns  of  segments,  and  each  segment 
represents  approximately  2  in  x  2  in  of  paper 
chart.  The  geographic  coverage  of  a  segment 
is  dependent  on  the  chart  scale  and  the  zone  in 
which  the  segment  is  located.  Lohrenz,  et  al. 

(1993)  describes  the  TS  projection  system  in 
more  detail,  and  Lohrenz  and  Ryan  (1990)  documents  the  CAC  file  structure.  The  reader  is 
advised  to  become  familiar  with  these  reports  prior  to  using  the  CAC  Access  Software. 

This  report  is  a  programmer's  reference  for  accessing  the  CAC  library  via  NRL-developed  CAC 
Access  Software,  which  is  a  user-callable  suite  of  utility  programs.  The  CAC  Access  Software 
was  written  in  ANSI  C  and  is  currently  running  under  the  following  operating  systems: 
Open  VMS,  Unix,  MS-DOS,  Windows  3.1,  Windows  95  and  Macintosh.  Appendices  A,  B,  and 
C  of  this  report  contain  the  entry  point  descriptions  for  the  High-Level,  Low-Level  and 
Miscellaneous  Access  Routines,  respectively.  Appendix  D  contains  the  High-Level  Function 
Calling  Order. 


Zone 

ID 

Zone  name 

Southern 

latitude 

Northern 

latitude 

0 

South  Polar 

90.00  S 

51.69  S 

1 

S.  Temperate 

51.69  S 

31.38  S 

2 

Equatorial 

31.38  S 

31.38  N 

3 

N.  Temperate 

31.38  N 

51.69  N 

4 

North  Polar 

51.69  N 

90.00  N 

Table  1 .  Available  CAC  scales  and  chart  series 


Scale 

Chart  Series 

1:5M 

1:2M 

1:1M 

1:500k 

1:250k 

1:100k 

1:50k 

Global  Navigation  Chart  (GNC) 

Jet  Navigation  Chart  (JNC) 
Operational  Navigation  Chart  (ONC) 
Tactical  Pilotage  Chart  (TPC) 

Joint  Operational  Graphics  (JOG) 
Topographic  Line  Map  (TLM)  - 100 
TLM-50 

Table  3.  CAC  library  installments  as  of  September,  1995. 


MDFF  Library  It 

DMA  Stock  It 

®cf-  Geographic  Coverage 

Date  1 

I  GNC(1:5M  scale)  ~~  | 

1  CD-I  995-A-MAP6-00033  ACNxxGNCxxOI 

1 

Worldwide  coverage 

09/95 

|  JNC(1:2M  scale)  | 

CD-I  991 -B-MAP5-1 0006 

ACNxxJNCxxOI 

1 

N/S  Am.,  Greenland,  Australia,  USSR 

10/91 

CD-I  992-A-MAP5-00008 

ACNxxJNCxx02 

1 

Europe,  USSR,  Africa,  China.  Japan 

03/92 

I  ONC  (1:1,000,000  scale) 

CD-I  994-A-MAP4-00032 

ACNxxONCxxOI 

1 

Eurasia 

9/94 

CD-I  991 -A-MAP4-0001 0 

ACNxxONCxx02 

1 

N/S  Am.,  Greenland,  Iceland,  Arctic  O. 

08/92 

CD-I  994-A-MAP4-00031 

ACNxxONCxx03 

1 

India,  Indonesia,  S.Pacific 

08/94 

CD-I  994-A-MAP4-00030 

ACNxxONCxx04 

1 

Africa,  Saudi  Arabia 

07/94 

CD-I  994-A-MAP4-00029 

ACNxxONCxx05 

1 

S.America,  Australia.  So.  Pacific 

05/94 

f  JOG  (1:250,000  scale)  "— | 

CD-I  991 -A-MAP2-1 0007 

ACNxx1501A09 

1 

Western  U.S. 

11/91 

CD-I  992-A-MAP2-00009 

ACNxx1501A10 

1 

Eastern  U.S. 

04/92 

CD-I  993-A-M  AP2-000 1 6 

ACNxx1501A16 

1 

Sea  of  Japan 

03/93 

CD-I  993-A-MAP2-000 1 7 

ACNxx1501A2021 

1 

S.  China  Sea 

03/93 

CD-I  993-A-MAP2-000 1 8 

ACNxx1501A27 

1 

Somalia/Ethiopia 

04/93 

CD-I  993-A-MAP2-000 1 9 

ACNxx1501A12 

1 

Western  Mediterranean 

05/93 

CD-I 993-A-MAP2-00020 

ACNxx1501A19 

1 

Saudi  Arabia 

05/93 

CD-I  993-A-MAP2-00022 

ACNxx1501A23 

1 

Caribbean 

07/93 

CD-I  993-A-MAP2-00023 

ACNxx1501A13 

1 

Black  Sea  &  Caspian  Sea 

09/93 

CD-I  993-A-MAP2-00024 

ACNxx1501A22 

1 

Central  America 

09/93 

CD-I  994-A-MAP2-00026 

ACNxx1501A04 

1 

U.K.  &  Baltic 

02/94 

CD-I 993-A-MAP2-00027 

ACNxx1501A08 

1 

Alaska 

02/94 

CD-I  994-A-MAP2-00028 

ACNxx1501A14 

1 

Afghanistan  &  NE  Iran 

05/94 

I  TPC  (1:500,000  scale) 

CD-I  995-C-MAP3-1 0001 

ACNxxTPCxx07 1 0 

3 

Update  of  U.S.t  Caribbean,  and  Panama 

09/95 

CD-I  991 -B-MAP3-1 0002 

ACNxxTPCxx0309A 

2 

Update  of  Desert  Storm 

06/91 

CD-I  991 -A-MAP3-1 0003 

ACNxxTPCxx0512A 

1 

W.  Pacific  Rim  &  Hawaii 

03/91 

CD-I  991 -A-MAP3-1 0004 

ACNxxTPCxx0506 

1 

No.  Pacific  (incl.  Alaska  &  NE  USSR) 

04/91 

CD-I  991 -A-MAP3-1 0005 

ACNxxTPCxx0208A 

1 

Med.,  Europe,  Scandinavia,  Iceland 

06/91 

CD-1992-A-MAP3-0001 1 

ACNxxTPCxx041 1 A 

1 

India  and  China 

10/92 

CD-I  992-A-MAP3-0001 2 

ACNxxTPCxx0304 

1 

W.  Russia  and  E.  Mongolia 

11/92 

CD-1992-A-MAP3-0001 3 

ACNxxTPCxx0405 

1 

Siberia 

01/93 

CD-I  992-A-M  AP3-000 1 4 

ACNxxTPCxx1216 

1 

Australia,  E.  Indonesia 

01/93 

CD-I  992-A-MAP3-000 1 5 

ACNxxTPCxxl  014 

1 

S.  America 

01/93 

CD-I  993-A-M AP3-0002 1 

ACNxxTPCxx0809 

1 

N.  Central  Africa 

07/93 

CD-I  993-A-MAP3-00025 

ACNxxTPCxx091 5 

J _ [ 

Southern  Africa  and  Madagascar 

10/93 

2 


CAC  Access  Software 


The  CAC  Access  Software  is  made  up  of  twelve  files,  including  four  C  programs  (*.c)  and  eight 
include  files  (*.h),  as  listed  in  table  3.  The  CAC  Access  Software  is  designed  to  allow  a 
programmer  both  high-level  and,  if  necessary,  low-level  access  to  a  CAC  CDROM.  The  high- 
level  routines  will  be  sufficient  for  most  applications,  but  a  user  may  require  low-level  access  for 
more  advanced  applications  that  manipulate  the  image  data. 


Table  3.  CAC  Access  Software  files. 


Programs 

Description 

Support  files 

cac_hlev.c 

High  level  CAC  access  routines 

cacjlev.c 

Low  level  CAC  access  routines 

cac_misc.c 

Routines  to  access  non-image  CAC 

areadrc.h, 

data  files  (e.g.,  audit  trail  files) 

areasorc.h, 

cd_header.h, 

dr_header.h, 

sg_header.h, 

pa.h 

C  language  structures  and  definitions; 
required  by  all  four  high-level  programs 

cacjnc.h 

Definitions  for  TS  projection  system; 
required  by  all  four  high-level  programs 

m4_const.h 

High-Level  Access  Routines 

The  high-level  CAC  access  routines,  which  are  contained  in  the  file  cac  hlsv .  c,  consist  of 
four  entry  points.  cac_init,  cac  inq _palette,  cac get  ll,  and  cac  get  rc.  These  routines  initialize 
the  software,  read  the  appropriate  color  palette,  and  retrieve  the  compressed  CAC  data  for  either 
a  specific  geographic  point  (latitude  and  longitude)  or  segment  (row  and  column).  The  high- 
level  routines  will  suffice  for  most  user  applications,  such  as  displaying  CAC  data.  Examples  of 
the  recommended  calling  sequences  for  these  high-level  routines  are  provided  in  the  files 
ma-'-n—rc  •  c>  main_ll .  c  (listed  in  Appendix  D).  Appendix  A  documents  the  high-level 
routines  in  detail.  They  and  listed  here  in  the  intended  calling  sequence: 

♦  cacinit 

Initializes  the  CAC  retrieval  software  by  allocating  the  necessary,  memory  for  segment 
buffering,  reading  the  cd_id .  dat  and  cd_covrg .  dat  files  from  the  ID  directory  on  the 
specified  device,  and  initializing  the  internal  CAC  data  structures  based  on  the  contents  of  the 
cd_id .  dat  and  cd_covrg .  dat  files. 

♦  cac_inq_palette 

Reads  and  returns  the  "day",  "night"  or  "mono"  color  palette  that  corresponds  to  the  retrieved 
CAC  segment  data.  Each  CAC  color  palette  file  includes  three  separate  palettes:  the  day 
palette  is  appropriate  for  daytime  flight,  the  night  palette  is  used  for  nighttime  flight,  and  the 
mono  palette  uses  only  gray  shades.  See  Lohrenz,  et  al.,  for  more  information  about  CAC 
color  palettes. 
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♦  cac_get_ll 

Retrieves  the  pixel  value  specified  by  latitude  and  longitude 
decompressed  segment,  if  required. 


Also  retrieves  the  entire 


♦  cac_get_rc 

Retrieves  the  entire  decompressed  segment  specified  by  a  TS  row,  column  and  zone. 


Both  cacjretjl  and  cac_get_rc  return  the  palette  identifier  for  the  color  palette  reauired  to 
display  the  data.  If  die  user  requests  an  invalid  latitude  and  longitude  coordinate  from  cac  get  ll 
or  an  invalid  row  and  column  from  cacjptjc  the  function  will  return  an  error  state 


Low-Level  Access  Routines 


The  low-level  CAC  access  routines,  which  are  contained  in  the  file  cac  llev .  c  consist  of  21 
entry  points.  These  low-level  routines  are  used  by  the  high-level  software  presented  in  the 
previous  section  In  addition,  programmers  that  need  to  manipulate  CAC  data  for  more  advanced 

“TvT  T  7^  l0W'!T[aCCeSS  r0UtineS-  B  documents  thZ  rortnl  n 

detail.  They  are  listed  here  in  alphabetical  order,  since  the  calling  sequence  may  varv  between 
applications.  All  floating  point  numbers  are  “double”  in  C.  " 

♦  cac Jree 

^  allocatedby  **  low-level  access  routines.  This  function  is  called  by 
the  high-level  routine  cacjmt  to  free  memory  associated  with  the  buffering  of  segment  data. Y 

♦  decode_key 

hS  r°W  311(1  C°1Umn  comP°nents-  A  TS  keyname  is  an  encoded 
yS.row  md  c,oIumn  311(1 1S  ^  t0  generate  the  filename  for  the  TS  segment  of 
mterest  (see  Lohrenz,  et  al.,  1993,  for  more  information  about  TS  keynames  and  filenames) 
The  inverse  function  is  encode  key.  SJ' 

♦  decompress  segment 

Reads  the  compressed  CAC  segment  and  its  codebook,  then  decompresses  the  segment 

♦  double Josi 

number ‘°  2  in,e8«  (Note:  this  function  reduces  the 

precision  of  the  data).  The  inverse  function  is  sijo  double. 

♦  encode_key 

^ncCo°jeeS^Segment  row  number  column  number  into  a  keyname.  The  inverse  function  is 

♦  eq2pol 

Concerts  equatorial  zone  latitude  and  longitude  coordinates  into  polar  zone  latitude  and 
longitude  coordinates  (see  Lohrenz,  et  al.,  1993,  for  more  information  about  TS  polar  and 
non-polar  coordinate  systems).  The  inverse  function  is  pol2eq. 

♦  get  decompressed _pixel 

*r:r  ™  speci?ed  Plxel  from  a  comPressed  segment  without  decompressing  the  entire 
segment.  This  is  done  by  computing  the  location  of  the  compressed  data  byte  in  a  two- 
dimensional  array  of  compressed  data  bytes,  given  the  pixel’s  x  and  y  coordinates. 
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♦  get_segment_name 

“ecZ  „z:  "  ■” direc,ory  name’ 

♦  latlon_calc 

is  rc_calc.  °  venaP  areas.  The  inverse  function 

♦  load_legend_data 

to  the  begiZngof 

the  size  in  rows  and  columns  of  the  legend  image  itself.  n>  “”<1  blue  (RGB)  buffers  and 

♦  pol2eq 

sees:  “e“^strr,es  ,o "  -  '  - 

♦  rc_calc 

♦  readjcdjcovrg 

Reads  the  cd_covrg.dat  file  from  the  ID  directory  on  the  CAT  rn T?m/r  ™ 
the  CAC^D^M^^ A^PA’s^sockt^TS^ C°Verage^  for  each  V***  area 

sss 

ttCD- 1 99 1  - A-MAP3 - 1 0004.  Tie  s^ucZe  »„o  Ze  ”  in  oZ  «'e  Was  MDFF '^ary 
PA  and  zone  number  associations  for  all  pap  a  a  *•  —  ^ev* c?  contains  the 

TTte  cd_id . dat  Z  “  *££ Z  T (C^>-A.MAr3- 10004). 

cd_covrg.  dat  file.  -  djd)  to  correctly  process  the 

♦  read_cdjd 

Reads  the  cd_id .  dat  file  from  the  ID  directory  on  the  CAC  CDROM. 

♦  read_compressed_segment 

Reads  the  compressed  segment  and  its  codebook  and  buffers  them  •  - 

The  number  of  segments  that  can  be  buffered  ^ontroUed  bvThe  1  “  “7  °f ' T"®*8* 
high-level  routine  cac  init  R11«hrJ„„  1  ed  W  the  argument  passed  to  the 

reading  an  oZ-uZZZm  8  S~  "d“*  -oived  in 

♦  read _palette 

Reads  and  returns  the  day  ,  "night"  or  "mono"  color  palette  for  the  retrieved  CAC  segment 

♦  read_entire _palette 
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♦  read _pa_coverage 

Reads  the  scaled  integer  latitude  and  longitude  coordinates  from  the  current  PA's 
coverage .  dat  file,  and  returns  them  as  floating-point  numbers. 


♦  remap _palette 

rlTr,2,0  KC4  0l<Jr  pa!ette  (24°  entries)  t0  “  al«ebraic  palette  (216  entries)  to  allow  the 
CAC  data  to  be  displayed  without  color  flicker.  The  color  flicker  is  caused  by  an  application 

using  put  the  enure  systems  color  paleue.  The  result  returned  is  an  array  of  indices  that  point 
to  the  algebraic  color  that  is  closest  to  the  CAC  palette  color  specified. 

♦  si_convert 

Converts  a  latitude  or  longitude  value  from  an  ASCII  string  to  a  scaled  integer.  The  format  of 
the  string  is  SDDDMMSS.SS  where: 


S  sign  of  the  latitude  or  longitude  (+  or  must  be  present  in  the  string)- 

ODD  =  degree  portion  (000  -  090  for  latitude,  or  000  -  1 80  for  longitude)-  ’ 
MM  =  minutes  portion  (00  -  59); 

SS .  SS  =  seconds  portion  (00.00  -  59.99). 


♦ 


♦ 


si_to_double 

Converts  a  scaled  integer  to  a  floating-point  number.  The  inverse  function  is  double _to_si 
spdec 


Decompresses  a  CAC  compressed  segment.  Due  to  the  peculiarities  of  MSDOS 
has  two  different  modes  (one  for  MSDOS,  and  one  for  VMS  and  Unix). 


this  routine 


Miscellaneous  Access  Routines 


The  miscellaneous  CAC  access  routines,  which  are  contained  in  the  file  cac_misc  c  consist 
ot  five  entry  points.  These  routines  are  used  to  access  the  audit  trail  data  on  a  CAC  CDROM. 

rrvpruk/f  pr0Vldef  a  path  back  t0  ^  original  paper  charts  used  to  create  the  ADRG 
™Q8F0M  ™re  Ration  about  specific  ADRG  files  referenced  in  this  section,  refer  to 
N1MA  (1989).  Appendix  C  documents  these  routines  in  more  detail. 


♦  read_areadrc 

Reads  the  specified  areadrc .  dat  file.  This  file  contains  a  list  of  the  CAC  CDROM  path 
names  of  the  Distribution  Rectangle  (DR)  files  for  each  ADRG  source  CDROM  in  a 
particular  scale  and  zone.  This  list  can  be  used  to  locate  the  ADRG  DR  information  for  a 
particular  area  of  the  CAC  CDROM. 


♦  readjareasorc 

Reads  the  specified  areasorc .  dat  file.  This  file  contains  a  list  of  the  CAC  CDROM  path 
names  of  the  Source  Graphic  files  for  each  DR  from  a  source  ADRG  CDROM  in  a  particular 

scale  and  zone.  This  list  can  be  used  to  locate  the  ADRG  source  information  for  a  particular 
area  of  the  CAC  CDROM. 


♦  read_cdheader 

Reads  the  specified  CD  header .  dat  file, 
specific  ADRG  source  CDROM. 


This  file  contains  various  information  about  a 
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♦  read_drheader 

Reads  the  specified  DR  header .  dat  file.  This  file  contains  information  about  a  specific 
DR  for  an  ADRG  source  CDROM. 

♦  read_sgheader 

Reads  the  specified  sgghed.dat  file.  The  gg  in  the  filename  is  the  source  graphics 

number  (01  -  99).  The  Source  Graphics  file  contains  information  about  the  original  paper 
chart  that  was  scanned  into  the  ADRG  CDROM. 
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Appendix  A:  Entry  Point  Descriptions  for  High-Level  Access 

Routines 

Note:  byte  is  typedefed  as  unsigned  char. 


cac_init . 

cac_inq_palette 

cac_get_ll . 

cac_get_rc . 


..9 

..9 

10 

10 


8 


cac  init 


short  cac_init  ( char  cac_device  [ ], 
int  numbuffers ) 

cac_device:  Name  of  device  that  CAC  CDROM  is  loaded  on. 
(char[  ],  passed) 

numjbuffers:  Number  of  segments  that  can  be  buffered  at  a  time, 
(int,  passed) 

Returns:  1:  Normal. 

- 1 :  Error  reading  CD_ID.DAT. 

-2:  Error  reading  CD_COVRG.DAT. 

-3:  Error:  CDROM  is  not  a  valid  CAC  CDROM. 


cac  inq  palette 

short  cac  inq  palette  ( char  type, 

short  palid, 
short  *size, 
byte  red  [  ], 
byte  green  [  ], 
byte  blue  []) 

type:  Type  of  palette  to  load  (DAY,  NIGHT,  or  MONO) 

(char,  passed) 

palid:  Palette  identification.  This  is  a  four  digit  number  identifying  the  color  palette 
to  use  for  the  selected  segment. 

(int,  passed) 

size:  Size  of  the  color  palette  returned. 

(short  *,  returned) 

red:  Array  of  size  size  containing  the  RED  component  of  the  color  palette. 

(byte  [  ],  returned) 

green:  Array  of  size  size  containing  the  GREEN  component  of  the  color  palette. 

(byte  [  ],  returned) 

blue:  Array  of  size  size  containing  the  BLUE  component  of  the  color  palette. 

(byte  [  ],  returned) 

Returns:  1:  Normal. 

-1 :  Error  opening  PALETTE.DAT  file. 

-2:  Error  reading  PALETTE.DAT  file. 
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cacjgetJU 


short  cac_get_ll (double  Ion, 
double  lat, 
short  *palid, 
short  *color ) 

Ion :  Longitude  of  requested  pixel. 

(double,  passed) 

lat:  Latitude  of  requested  pixel. 

(double,  passed) 

pal  id:  Palette  identification  of  pixel  at  the  specified  lat  and  Ion. 

(short  *,  returned) 

color:  Pixel  value  at  specified  lat  and  Ion.  This  is  the  index  into  the  color  palette, 
(short  *,  returned) 

Returns:  1:  Normal 

-1:  Error:  specified  (lat,  Ion )  point  does  not  fall  within  bounds  specified  by 
CD_COVRG.DAT  file.  I.e.,  the  specified  data  is  not  on  the  CDROM. 


cacgetrc 


short  cac  get  rc  ( long  row, 
long  col, 
short  mapzone, 
short  *palid) 

row:  Row  of  requested  segment. 

(long,  passed) 

col:  Column  of  requested  segment. 

(long,  passed) 

map_zone:  TS  map  zone  that  the  requested  segment  is  in.  This  is  used  to  allow  specifying 
segments  in  zone  overlap  areas. 

(short ,  passed) 

palid:  Palette  identification  of  segment  at  row/col. 

(short  *,  returned) 

Returns:  1:  Normal 

-1 :  Error:  specified  map  zone  is  not  on  this  CDROM. 

-2:  Error:  specified  segment  at  row/col  is  not  on  this  CDROM. 
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Appendix  B:  Entry  Point  Descriptions  for  Low-Level  Access  Routines 


cac_free . 

decode_key . 

decompress_segment . 

double_to_si . 

encode_key  . 

eq2pol . 

get_decompressed_pixel ... 

getsegmentname . 

latloncalc . 

load_legend_data . 

pol2eq . 

rc_calc . 

read_cd_covrg . 

read_cd_id . . 

read_compressed_segment. 

read_pa_coverage . 

read_palette . 

remap_palette . 

si_convert . 

si_t°_double . 

spdec . 


..12 

..12 

..12 

..12 

..13 

..13 

,14 

,14 

.15 

.16 

.17 

.17 

.18 

.18 

.19 

.19 

.20 

.20 

.21 

.21 

.22 
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cac Jree 

void  cac Jree  (void) 
Returns:  None. 


decode_key 


void  decode_key  (char  keyname  [ J, 
long  *row, 
long  *col ) 


keyname:  Keyname  to  decode, 
(char  [  ],  passed) 


row:  Row  number  to  encode, 
(long  *,  returned) 

col:  Column  number  to  encode, 
(long  *,  returned) 

Returns:  None. 


decompressjsegment 

short  decompress  segment  ( char  pa _path[], 

unsigned  char  *decomp_seg ) 

pa _path:  Complete  file  specification  of  CAC  segment  file  to  decompress, 
(char  [  ],  passed) 

decomp  seg:  Pointer  to  array  containing  the  decompressed  segment  data, 
(unsigned  char  *,  returned) 

Returns:  1:  Normal 

-1 :  Error  reading  the  compressed  segment  file. 


double_to_si 

long  double_to_si  (double  value) 

value:  Double  precision  number  to  convert  to  a  Scaled  integer, 
(double,  passed) 

Returns:  Encoded  scaled  integer  as  a  signed  long. 
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encodejkey 


void  encodekey  ( long  *row, 
long  *col, 
char  keyname  []) 


row:  Row  number  to  encode, 
(long  *,  passed) 

col:  Column  number  to  encode, 
(long  *,  passed) 

keyname:  Resultant  encoded  keyname, 
(char  [  ],  returned) 


Returns:  None. 


eq2pol 


void  eq2pol  (double  *latin, 
double  *longin, 
double  *latout, 
double  *longout, 
short  *zone ) 

latin:  Equatorial  latitude  to  convert, 
(double  *,  passed) 

longin:  Equatorial  longitude  to  convert, 
(double  *,  passed) 

latout:  Polar  latitude. 

(double  *,  returned) 

longout:  Polar  longitude. 

(double  *,  returned) 

zone:  Polar  zone  to  use  in  the  conversion, 
(short  *,  passed) 

Returns:  None. 
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getjdecompressed _pixel 

short  getjdecompressed _pixel  (  short  y, 

short  x ) 

y:  Y  coordinate  of  a  pixel  in  the  compressed  segment. 

(short ,  passed) 

x :  X  coordinate  of  a  pixel  in  the  compressed  segment. 

(short,  passed) 

Returns:  Short  integer  corresponding  to  the  X  and  Y  coordinates  of  the  requested  pixel. 


getsegmentname 

void  getsegmentname  ( char  pa _path[J, 

long  row, 
long  col, 
short  zone, 
char  seg_path  [  ] ) 

pa _path:  Path  to  the  palette  area  subdirectory. 

(char  [  ],  passed) 

Note  the  character  at  the  end  of  VMS  path  names,  and  the  “/  ”  or  “  \”  in 
Unix  or  MS-DOS  filenames.  The  following  are  sample  paths  to  the  same 
palette  area  subdirectory  on  VMS,  Unix,  and  MS-DOS  systems: 

VMS:  CDROM:  [MAP3JPA012901. 

Unix:  /cdrom/map3/pa012901/ 

MSDOS:  D:\map3\pa012901\ 

row.  Row  number  of  segment  to  decompress. 

(long,  passed) 

col :  Column  number  of  segment  to  decompress. 

(long,  passed) 

zone:  Tesselated  Sphere  zone  number  cooresponding  to  pa _path. 

(short,  passed) 

seg_path :  Complete  path  specification  for  requested  segment. 

(char  [  ],  returned) 

Eg.,  VMS:  CDROM: [MAP3.PA012901.R000015]  12345678.214 
Unix:  /cdrom/map3/pa012901/r000015/12345678.214 

MSDOS:  D:\map3\pa012901\r000015\12345678.214 


Returns:  None. 


14 


latlon  calc 


void  latlon_calc  (short  *zone, 
short  *scale, 
long  *row, 
long  *col, 
double  Hat, 
double  Hon) 

zone:  Zone  to  use  in  the  conversion  to  latitude/longitude, 
(short  *,  passed) 

scale :  Scale  to  use  in  the  conversion  to  latitude/longitude, 
(short  *,  passed) 

row:  Tesselated  sphere  row  number  to  convert. 

(long  *, passed) 

col:  Tesselated  sphere  column  number  to  convert. 

(long  *, passed) 

lat:  Latitude  based  on  scale,  zone,  row  and  column, 
(double  *,  returned) 

Ion:  Longitude  based  on  scale,  zone,  row  and  column, 
(double  *,  returned) 

Returns:  None. 


load_legend_data 

void  load_legend_data  (char  legend _path  [  J, 

unsigned  char  **legend _ptr, 
unsigned  char  rbuf  [ ], 
unsigned  char  gbuf  [  J, 
unsigned  char  bbuf  [  ], 
unsigned  long  *legend_x, 
unsigned  long  *legend_y) 

legend _path :  File  specification  of  the  directory  containing  the  legend  data. 

(char  [  ],  passed) 

legend  jptr :  Pointer  to  the  beginning  of  the  array  containing  the  legend  image  data, 
(unsigned  char  **,  returned) 

rbuf.  Red  component  of  the  legend  image's  palette. 

(unsigned  char  [  ],  returned) 

gbuf:  Blue  component  of  the  legend  image's  palette. 

(unsigned  char  [  ],  returned) 

bbuf  Green  component  of  the  legend  image’s  palette. 

(unsigned  char  [  ],  returned) 

legendjc:  Size  of  the  legend  image  in  the  "x"  direction  (columns). 

(unsigned  long  *,  returned) 

legend_y :  Size  of  the  legend  image  in  the  "y"  direction  (rows). 

(unsigned  long  *,  returned) 

Returns:  1:  Normal 

-1 :  Error  opening  legend  header  file. 

-2:  Error  reading  legend  header  file. 

-3:  Error  opening  legend  image  file. 

-4:  Error  reading  legend  image  file. 
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pol2eq 


void  polleq  (double  *latin, 
double  Hongin, 
double  *latout, 
double  Hongout ) 

latin:  Polar  latitude  to  convert, 
(double  *,  passed) 

longin'.  Polar  longitude  to  convert, 
(double  *,  passed) 

latout:  Equatorial  latitude, 
(double  *,  returned) 

longout :  Equatorial  longitude, 
(double  *,  returned) 

Returns:  None. 


rc  calc 


void  rc  calc  ( double  Hat, 
double  Hon, 
short  *scale, 
short  Hone, 
long  How, 
long  *col) 

lat:  Latitude  to  convert. 

(double  *,  passed) 

Ion:  Longitude  to  convert. 

(double  *,  passed) 

scale:  Scale  to  use  in  the  conversion  to  row/column. 

(short  *,  passed) 

zone:  Zone  to  use  in  the  conversion  to  row/column. 

(short  *,  passed) 

col:  Tesselated  sphere  column  number  based  on  specified  scale  and  zone, 
(long  *, returned) 

row:  Tesselated  sphere  row  number  based  on  specified  scale  and  zone, 
(long  *, returned) 

Returns:  None 
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read_cd_covrg 

short  read  cd  covrg  (char  path[  ], 

char  pa_mims[MAX_PAS][8], 
short  *num  _pas, 
double  pa_latlon[MAX_PAS][4], 
char  pa_zones[MAX_PAS] ) 

path :  Complete  path  specification  to  the  CDROM’s  CD_COVRG.DAT  file. 

(char  [  ],  passed) 

pajiums :  Two-dimensional  array  of  palette  area  names  from  the  CD_COVRG.DAT  file. 

Each  palette  area  name  is  eight  bytes.  The  maximum  number  of  possible 
palette  areas  on  one  CDROM  is  MAX  PAS  (see  CACINC.H). 

(char  [  ][8],  returned) 

mm  jpas :  The  number  of  palette  areas  on  the  CDROM. 

(short  *,  returned) 

pajatlon :  Two  dimensional  array  of  approximate  coverages  of  each  palette  area  on  the 
CDROM.  The  order  of  the  latitude/longitude  data  in  the  array  is  as  follows: 
[*][0]  =  West  longitude 
[*][1]=  East  longitude 
[*][2]  =  South  latitude 
[*][3]  =  North  latitude 
(double  [  ][4],  returned) 

pazones:  Array  of  TS  zone  numbers  corresponding  to  pa  nums  above. 

(char  [  ],  returned) 

Returns:  1:  Normal 

-1:  ErroropeningCD_COVRG.DAT  file. 

-2:  Error  reading  the  number  of  palette  areas  from  CD_COVRG.DAT  file. 

-3:  Error  reading  a  palette  area  name  from  CD_COVRG.DAT  file. 

-4:  Error  reading  a  palette  area  lat/lon  set  from  CD_COVRG.DAT  file. 


read_cd_id 


short  read  cd  id (char  path[ ], 
char  dataf  ] ) 

path :  Complete  path  specification  to  the  CDROMs  CD_ID.DAT  file, 
(char  [  ],  passed) 

data:  Contents  of  specified  CD_ID.DAT  file. 

(char  [  ],  returned,  requires  twenty  bytes) 

Returns:  1:  Normal 

-1:  ErroropeningCD_ID.DAT  file. 

-2:  Error  reading  CD_ID.DAT  file  . 
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read_compressed_segment 

short  read_compressed_segment  (char  pa _path[ ], 

unsigned  char  *codebook, 
unsigned  char  *compseg ) 

pa _path:  Complete  file  specification  of  CAC  segment  file  of  interest. 

(char  [  ],  passed) 

codebook:  Codebook  to  decompress  segment  (codebook  requires  1024  bytes  of  memory), 
(unsigned  char  *,  returned) 

compseg:  Compressed  segment  to  be  decompressed  (compressed  segment  requires  16384 
bytes  of  memory). 

(unsigned  char  *,  returned) 

Returns:  1:  Normal 

-1:  Error  opening  compressed  CAC  segment  file. 

-2:  Error  reading  compressed  CAC  segment  codebook. 

-3:  Error  reading  compressed  CAC  segment  data. 


read _pa_coverage 

short  read _pa_coverage  (  char  namef  ], 

double  *minlon, 
double  *maxlon, 
double  *minlat, 
double  *maxlat ) 

name:  PA  coverage  filename  (full  path). 

(char  [  ],  passed) 

Eg.,  VMS:  CDROM: [MAP3.PA012901JCOVERAGE.DAT 
Unix:  /cdrom/map3/pa012901/coverage.dat 

MSDOS:  D:\map3\pa012901\coverage.dat 

minion:  Minimum  longitude  coordinate. 

(double  *,  returned) 

maxlon:  Maximum  longitude  coordinate. 

(double  *,  returned) 

minlat:  Minimum  latitude  coordinate. 

(double  *,  returned) 

maxlat:  Maximum  latitude  coordinate. 

(double  *,  returned) 

Returns:  1:  Normal 

-1:  Error  opening  PA  COVERAGE.DAT  file. 

-2:  Error  reading  PA  COVERAGE.DAT  file  . 
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read _palette 


short  read _palette  (char  type, 

char  path[], 
unsigned  char  red[  J, 
unsigned  char  greenf  J, 
unsigned  char  blue[ ] ) 

type:  Color  palette  type  (day,  night,  mono). 

(char,  passed) 

path:  Complete  file  specification  of  CAC  color  palette. 

(char  [  ],  passed) 

red:  Red  component  of  color  palette  (requires  at  least  256  bytes), 
(unsigned  char  *,  returned) 

green:  Green  component  of  color  palette  (requires  at  least  256  bytes), 
(unsigned  char  *,  returned) 

blue:  Blue  component  of  color  palette  (requires  at  least  256  bytes), 
(unsigned  char  *,  returned) 

Returns:  1:  Normal 

-1 :  Error  opening  CAC  color  palette. 

-2:  Error  reading  CAC  color  palette. 


remap _palette 

unsigned  char  *remap _palette  ( unsigned  char  red[  J, 

unsigned  char  green[ ], 
unsigned  char  bluef  ]) 

red:  Red  component  of  color  palette  to  remap. 

(unsigned  char  *,  returned) 

green  :  Green  component  of  color  palette  to  remap. 

(unsigned  char  *,  returned) 

blue  :  Blue  component  of  color  palette  to  remap. 

(unsigned  char  *,  returned) 

Returns:  Pointer  to  an  array  containing  indices  that  represent  the  mapping  of  the 
specified  CAC  color  map  entries  to  the  nearest  color  in  an  algebraic  color  map. 
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si  convert 


long  si_convert  (char  value[  ], 
short  type) 

value:  Character  string  of  latitude  or  longitude  to  convert  to  a  scaled  integer  number. 
The  sign  of  the  latitude  and  longitude  value  (i.e., "+"  or  must  be  present, 
(char  [  ],  passed) 

type:  Denotes  whether  value  is  a  longitude  or  latitude  (0  =  longitude,  1  =  latitude). 
(enum{longitude, latitude},  passed) 

Returns:  The  scaled  integer  of  value  is  returned  as  a  signed  long. 


si_to_double 

double  si_to_double  (long  si) 

si:  Scaled  integer  to  be  converted  to  a  double, 
(long,  passed) 

Returns:  Double  equivalent  of  decoded  scaled  integer. 
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spdec 


VMS  and  Unix  usage: 

void  spdec  ( unsigned  char  inptr[ 16384], 

unsigned  char  spcbptr] 16384], 
unsigned  char  outptr[65536] ) 

inptr.  Compressed  segment  (assumed  to  be  16384  bytes)  to  be  decompressed, 
(unsigned  char  [  ],  passed) 

spcbptr-.  Codebook  (assumed  to  be  1024  bytes)  to  decompress  the  segment, 
(unsigned  char  [  ],  passed) 

outptr:  Decompressed  segment  (requires  65536  bytes). 

(unsigned  char  [  ],  returned) 

Returns:  None. 


MSDOS  usage: 

void  spdec  (  unsigned  char  far  inptr [16384], 

unsigned  char  far  spcbptr [16384], 
unsigned  char  far  outptr [65 5 36] ) 


inptr:  Compressed  segment  (assumed  to  be  16384  bytes)  to  be  decompressed, 
(unsigned  char  far  [  ],  passed) 

spcbptr:  Codebook  (assumed  to  be  1024  bytes)  to  decompress  the  segment, 
(unsigned  char  far  [  ],  passed) 

outptr:  Decompressed  segment  (requires  65536  bytes). 

(unsigned  char  far  [  ],  returned) 

Returns:  None. 
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Appendix  C:  Entry  Point  Descriptions  for  Miscellaneous  Access 

Routines 


readareadrc . 24 

read_areasorc .  24 

read_cdheader .  25 

read_drheader . 25 

read_sgheader .  25 
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read  areadrc 


Must  include  file  areadrc .  h . 

short  read  areadrc  (char  path[ J, 

struct  areadrc  *areadrc, 
short  *numpas ) 

path :  Complete  file  specification  of  the  AREADRC.DAT  file, 
(char  [  ],  passed) 

areadrc :  Structure  to  contain  data  read  from  AREADRC.DAT  file, 
(struct  areadrc  *,  returned) 

numpas:  Number  of  PA  areas  (zones)  in  the  AREADRC.DAT  file, 
(short  *,  returned) 

Returns:  1:  Normal 

-1:  ErroropeningAREADRC.DAT  file. 

-2:  Error  reading  AREADRC.DAT  file. 


readareasorc 

Must  include  file  areasorc .  h . 

short  read_areasorc  (char  pathf  J, 

struct  areasorc  *areasorc, 
short  *numpas) 

path:  Complete  file  specification  of  the  AREASORC.DAT  file, 
(char  [  ],  passed) 

areasorc:  Structure  to  contain  data  read  from  AREASORC.DAT  file, 
(struct  areasorc  * ,  returned) 

numpas:  Number  of  PA  areas  (zones)  in  the  AREASORC.DAT  file, 
(short  *,  returned) 

Returns:  1:  Normal 

-1:  Error  opening  AREASORC.DAT  file. 

-2:  Error  reading  AREASORC.DAT  file. 
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read_cdheader  (Must  include  file  cd_header .  h). 

short  readcdheader  (char  path[ J, 

struct  cdheader  *cdheader, 
short  *numpas ) 

path :  Complete  file  specification  for  the  CD  HEADER.DAT  file, 
(char  [  ],  passed) 

cdheader :  Structure  to  contain  data  read  from  CD  HEADER.DAT  file, 
(struct  cdheader  *,  returned) 


Returns:  1:  Normal 

-1:  Error  opening  CD  HEADER.DAT  file. 
-2:  Error  reading  CD  HEADER.DAT  file. 


readjdrheader  (Must  include  file  dr_header .  h). 

short  readdrheader  (char  path[ ] , 

struct  drheader  *drheader, 
short  *numpas) 

path.  Complete  file  specification  of  the  DR  HEADER.DAT  file, 
(char  [  ],  passed) 

drheader:  Structure  to  contain  data  read  from  DR  HEADER.DAT  file, 
(struct  drheader  *,  returned) 

Returns:  1:  Normal 

-1:  Error  opening  DR  HEADER.DAT  file. 

2:  Error  reading  DR  HEADER.DAT  file. 


readsgheader  (Must  include  file  sg_header .  h). 

short  read  sgheader  (char  pathf  ] , 

struct  sgheader  *sgheader, 
short  *numpas ) 

path:  Complete  file  specification  of  the  SG  HEADER.DAT  file, 
(char  [  ],  passed) 

sgheader:  Structure  to  contain  data  read  from  SG  HEADER.DAT  file, 
(struct  sgheader  *,  returned) 

Returns:  1:  Normal 

-1 :  Error  opening  SG  HEADER.DAT  file. 

-2:  Error  reading  SG  HEADER.DAT  file  . 
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Appendix  D:  High  Level  Function  Calling  Order 


main_ll.c . 27 

mainrc.c . 29 
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main  lie 


#include  "cac_inc.h" 

#include  "m4_const.h” 

int  main  (unsigned  int  arge,  char  *argv[  ]) 

{ 

short  size,  i; 
int  status; 
double  lat,lon; 
short  color; 

short  palid,  prev_palid=0; 
char  debug=0; 

static  unsigned  char  decomp_seg[256][256];  /*  Decompressed  CAC  segment  */ 

unsigned  char  red[256],  /*  Selected  color  palette  */ 

green[256], 
blue[256]; 

/*  argv[l]:  CDROM  device  name  */ 

/*  argv[2]:  Number  of  segments  to  buffer  */ 

cac_init  (argv[l],  atoi(argv[2])); 

while  (TRUE) 

{ 

printf("Lat,Lon  (separated  by  a  comma): "); 
scanf  ("%lf,%lf &lat,&lon); 
status  =  cac  get  ll  (Ion,  lat,  &palid,  &color); 
if  (status  =1) 

{ 

printf  ("Lat:  %6.21f  Lon:  %7.21f\n",  lat,  Ion); 
printf  ("Row:  %6d  Col:  %6d\n",  cac.row,  cac.col); 
printf  ("  Palette  ID:  %d\n",  palid); 
printf  ("Pixel  color:  %d\n",  color); 
if  (prev_palid  !=  palid) 

{ 

status  =  cac_inq_palette  (day,  palid,  &size,  red,  green,  blue); 
printf  ("Palette  loaded  for  PA#:  %d\n", palid); 
prevjpalid  =  palid; 
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if (debug) 

for  (i=0;  i<size;  i++) 

printf("%x  %x  %x\n",  red[i],green[i],blue[i]); 

} 

} 

else 

printf  ("Position  NOT  found  on  CAC..An"); 

}  /*  End  "while  (TRUE)"  */ 

} 
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main  rc.c 


#include  "cac_inc.h" 

#include  "m4_const.h" 

int  main  (unsigned  int  argc,  char  *argv[  ]) 

{ 

short  size,  i; 

unsigned  char  red[256],  /*  Selected  color  palette  */ 

green[256], 
blue[256]; 

int  status; 
long  row,col; 
short  color,  map_zone; 
short  palid,  prev_palid=0; 
char  debug=0; 

static  unsigned  char  decomp_seg[256][256];  /*  Decompressed  CAC  segment  */ 

/*  argv[l]:  CDROM  device  name  */ 

/*  argv[2]:  Number  of  segments  to  buffer  */ 

cac_init  (argv[l],  atoi(argv[2])); 

while  (TRUE) 

{ 

printf("Row, Column, Zone  (separated  by  commas): "); 
scanf  ("%ld,%ld,%d",  &row,  &col,  &map_zone); 

status  =  cac_get_rc  (row,  col,  map_zone,  &palid,  (unsigned  char  *)decomp_seg); 
if  (status) 

{ 

printf  ( "Row:  %61d  Col:  %61d\n",  row,  col); 
printf  ("  Palette  ID:  %d\n",  palid); 

printf  ("  cac.row:  %61d  cac.col:  %61d\n",  cac.row,  cac.col); 
if  (prev__palid  !=  palid) 

{ 

status  =  cac_inq_palette  (day,  palid,  &size,  red,  green,  blue); 
printf  ("Palette  loaded  for  PA#:  %d\n", palid); 
prevjpalid  =  palid; 
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if  (debug) 

for  (i=0;i<size;i++) 

printf  ("%x  %x  %x\n",red[i],green[i],blue[i]); 

} 

} 

else 

printf  ("Position  NOT  found  on  CAC.An"); 

}  /*  End  "while  (TRUE)"  */ 

} 
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